home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / formats / hdf / hdf1.txt < prev    next >
Text File  |  1980-02-06  |  9KB  |  266 lines
  1.  
  2.  
  3. Chapter 1    The Basic Structure of HDF Files
  4.  
  5.  
  6.  
  7. Chapter Overview
  8. File Header
  9. Data Object
  10. Data Descriptor
  11. DD Blocks
  12. Data Element
  13. Physical Organization of HDF Files
  14.  
  15. Chapter Overview
  16.  
  17. This chapter introduces and describes the components and 
  18. organization of Hierarchical Data Format files.
  19.  
  20.  
  21. File Header
  22.  
  23. The first component of an HDF file is the file header (FH), which 
  24. takes up the first four bytes in an HDF file. The file header is just a 
  25. signature that indicates that the file is an HDF file. Specifically, it 
  26. is the 32-bit magic number formed by the four characters ^N, ^C, 
  27. ^S, and ^A (hexadecimal value 0e031301).
  28.  
  29. NOTE:  On some machines the order of bytes in the file header 
  30. might be swapped when the header is written to an HDF file, 
  31. causing these characters to be written in the wrong order. To 
  32. maintain machine portability when developing software for such 
  33. machines, you should counteract this byte-swapping by making 
  34. sure the characters are read and written in the exact order shown.
  35.  
  36.  
  37. Data Object
  38.  
  39. The basic building block in an HDF file is the data object, which 
  40. contains both data and information about the data. A data object 
  41. has two parts:  a 12-byte data descriptor (DD) and a data element. 
  42. Figure 1.1 shows three examples of data objects.
  43.  
  44. As the names imply, the data descriptor gives information about 
  45. the data, and the data element is the data itself. In other words, all 
  46. data in an HDF file has attached to it information about itself. For 
  47. this reason, HDF files are examples of self-describing files.
  48.  
  49. Figure 1.1    Three Data Objects
  50.                                           
  51.  
  52.  
  53.  
  54. Data Descriptor (DD)
  55. A DD has four fields:  a 16-bit tag, a 16-bit reference number, a 32-
  56. bit data offset, and a 32-bit data length. These parts of a DD are 
  57. depicted in Figure 1.2 and are briefly described in Table 1.1. 
  58. Explanations of each part appear in the paragraphs following 
  59. Table 1.1.
  60.  
  61. Figure 1.2  A Data Descriptor (DD)
  62.                                         
  63.  
  64.  
  65.  
  66. Table 1.1    Parts of a Data 
  67. Descriptor
  68. Part    Description
  69. tag    designates the type of data in a data element
  70. reference number    uniquely distinguishes corresponding data 
  71. element from others with the same tag
  72. data identifier    tag/ref; uniquely identifies data element
  73. offset    byte offset of corresponding data element
  74. length    length of data element
  75.  
  76.  
  77. Tag
  78. A tag is the part of a data descriptor that tells what kind of data is 
  79. contained in the corresponding data element. A tag is actually a 
  80. 16-bit unsigned integer between 1 and 65535, but every tag is also 
  81. usually given a name that programs can refer to instead of the 
  82. number. If a DD has no corresponding data element, the value of 
  83. its tag is no data (ND). A tag may never be zero.
  84.  
  85. The extensibility of HDF results from the fact that new tags can be 
  86. assigned when it becomes necessary to store new types of data 
  87. elements. Tags are assigned by NCSA as part of the specification 
  88. of HDF. Appendix A contains full specifications for all currently 
  89. supported NCSA HDF tags.
  90.  
  91. As NCSA HDF grows, the number of tags grows. In addition to the 
  92. tags that are defined in this document, some tags are reserved for 
  93. experimentation and some are delegated to other individuals or 
  94. institutions in "round" intervals of 100's, 1000's, or 10,000's. All 
  95. numbers that are not already designated are reserved for future 
  96. definition by NCSA. Appendix B, "Assigned Tag Numbers," 
  97. contains the current number assignments.
  98.  
  99.  
  100. Reference Number
  101. For each occurrence of a tag in an HDF file, a unique reference 
  102. number is stored with the tag in the data descriptor. Reference 
  103. numbers are 16-bit unsigned integers.
  104.  
  105.  
  106. Data Identifier
  107. The combination of a tag and its reference number uniquely 
  108. identifies the corresponding data object in the file. For this reason, 
  109. the tag/ref combination is sometimes referred to as a data 
  110. identifier.
  111.  
  112.  
  113. Data Offset and Length
  114. The data offset reflects the byte offset of the corresponding data 
  115. element from the start of the file. The length gives the number of 
  116. bytes occupied by the data element. Offset and length are both 32-bit 
  117. unsigned integers.
  118.  
  119.  
  120. DD Blocks
  121. Data descriptors are stored physically in a linked list of blocks 
  122. called data descriptor blocks, or DD blocks. The individual 
  123. components of a data descriptor block are depicted in Figure 1.3. 
  124. All of the DDs in a DD block are assumed to contain significant 
  125. data unless they have a tag that is equal to ND (no data).
  126.  
  127. In addition to its DDs, each data descriptor block has a data 
  128. descriptor header (DDH). The DDH has two fields a block size 
  129. field and a next block field. The block size field is a 16-bit 
  130. unsigned integer that indicates the number of DDs in the following 
  131. DD block. The next block field is 32-bit unsigned integer giving 
  132. the offset of the next DD block, if there is one. The last DDH in the 
  133. list contains a 0 in its next block field.
  134.  
  135.  
  136. Figure 1.3    Model of a Data Descriptor Block
  137.  
  138.                                                            
  139.  
  140.  
  141.  
  142. Data Element
  143. A data element is the raw data part of a data object. Its basic data 
  144. type is determined by its tag, but other interpretive information 
  145. may be required before it can be processed properly.
  146.  
  147. Each data element is stored as a set of contiguous bytes starting at 
  148. the offset given in the corresponding DD. (See Figure 1.4/)
  149.  
  150.  
  151. Figure 1.4    Sample Data Descriptor Block
  152.  
  153.                                                            
  154.  
  155.  
  156.  
  157. Physical Organization of HDF Files
  158.  
  159. Physically, the file header, DD blocks, and data elements are 
  160. organized as follows. The file header is followed by the first DD 
  161. block, which is followed by data elements and, if necessary, more 
  162. DD blocks. These relationships are summarized in Table 1.2.
  163.  
  164. There are no rules governing the distribution of DD blocks and 
  165. data elements within a file, except that the first DD block must 
  166. follow immediately after the header. The pointers in the DD 
  167. headers connect the DD blocks in a linked list, and the offsets in 
  168. the individual DDs connect the DDs to the data elements. Beyond 
  169. this basic structure there is no necessary ordering among the 
  170. objects in an HDF file, although there are guidelines that you are 
  171. encouraged to follow. More information regarding these 
  172. guidelines is presented in Chapter 4, "HDF Conventions."
  173.  
  174. Table 1.2    Summary of the 
  175. Relationships 
  176. Among Parts of an 
  177. HDF File
  178. Part    Constituents
  179. HDF-file    FH, DD-block, data, DD-block, data, DD-block, data...
  180. FH    ^N ^C ^S ^A [32 bits]
  181. DD-block    DDH, DD, DD, DD...
  182. DDH    number-of-DDs [16 bits], offset-to-next-DD block [32 bits]
  183. DD    tag [16 bits], ref [16 bits], offset [32 bits], length [32 bits]
  184.  
  185.  
  186.  
  187. Example HDF File
  188. Consider an HDF file that contains two 400-by-600 8-bit raster 
  189. images. Typically, such a file might contain the objects described 
  190. in Table 1.3.
  191.  
  192. Table 1.3    Sample Data Objects 
  193. in an HDF File
  194. Tag    Ref    Data
  195. FID    1    file identifier:  user-assigned title for file
  196. FD    1    file descriptor:  user-assigned block of text
  197.         describing overall file contents
  198. IP8    1    image palette (768 bytes)
  199. ID8    1    x and y dimensions of the 2D arrays that contain    
  200.         the raster images (4 bytes)
  201. RI8    1    first 2D array of raster image pixel data (x*y bytes)
  202. RI8    2    second 2D array of pixel data (also x*y bytes)
  203.  
  204.  
  205. Assuming, for example, that the size of a DD block is 10 DDs, the 
  206. physical organization of the contents of the file might be described 
  207. as in Figure 1.5.
  208.  
  209. Figure 1.5    Physical 
  210.     Representation of Data 
  211.     Objects
  212.  
  213.  Offset    Contents
  214.     0    FH
  215.     4    DDH    (5    0L)
  216.     10    DD    (FID    1    130    4)
  217.     22    DD    (FD    1    134    41)
  218.     34    DD    (IP8    1    175    768)
  219.     46    DD    (ID8    1    943    4)
  220.     58    DD    (RI8    1    947    240000)
  221.     70    DD    (RI8    2    240947    240000)
  222.     82    DD    (empty)
  223.     94    DD    (empty)
  224.     106    DD    (empty)
  225.     118    DD    (empty)
  226.     130    "sw3"
  227.     134    "solar wind simulation: third try. 8/8/88"
  228.     175    <data for the image palette>
  229.     943    <data for the image dimensions>:  400, 600
  230.     947    <data for the first raster image>
  231.     240947    <data for the second raster image>
  232.  
  233.  
  234. In this instance, the file contains two raster images. The two 
  235. images have the same dimensions and are to be used with the same 
  236. palette. So, the same data objects for the palette (IP8) and 
  237. dimension record (ID8) can be used with both images.
  238.  
  239. 1.1    NCSA HDF Specifications
  240.  
  241. The Basic Structure of HDF Files    1.1
  242.  
  243. National Center for Supercomputing Applications
  244.  
  245. March 1989
  246.  
  247.                                                                 
  248.  
  249.  
  250.  
  251.  
  252. 1.1    NCSA HDF Specifications
  253.  
  254. The Basic Structure of HDF Files    1.1
  255.  
  256. National Center for Supercomputing Applications
  257.  
  258. March 1989
  259.  
  260.                                                                 
  261.  
  262.  
  263.  
  264.  
  265.  
  266.